.TH std::list::emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::list::emplace \- std::list::emplace

.SH Synopsis
   template< class... Args >                                \fI(since C++11)\fP
   iterator emplace( const_iterator pos, Args&&... args );

   Inserts a new element into the container directly before pos.

   The element is constructed through std::allocator_traits::construct, which uses
   placement-new to construct the element in-place at a location provided by the
   container.

   The arguments args... are forwarded to the constructor as
   std::forward<Args>(args).... args... may directly or indirectly refer to a value in
   the container.

   No iterators or references are invalidated.

.SH Parameters

   pos         -        iterator before which the new element will be constructed
   args        -        arguments to forward to the constructor of the element
.SH Type requirements
   -
   T (the container's element type) must meet the requirements of EmplaceConstructible.

.SH Return value

   Iterator pointing to the emplaced element.

.SH Complexity

   Constant.

.SH Exceptions

   If an exception is thrown (e.g. by the constructor), the container is left
   unmodified, as if this function was never called \fI(strong exception guarantee)\fP.

.SH Example


// Run this code

 #include <iostream>
 #include <string>
 #include <list>

 struct A
 {
     std::string s;

     A(std::string str) : s(std::move(str)) { std::cout << " constructed\\n"; }

     A(const A& o) : s(o.s) { std::cout << " copy constructed\\n"; }

     A(A&& o) : s(std::move(o.s)) { std::cout << " move constructed\\n"; }

     A& operator=(const A& other)
     {
         s = other.s;
         std::cout << " copy assigned\\n";
         return *this;
     }

     A& operator=(A&& other)
     {
         s = std::move(other.s);
         std::cout << " move assigned\\n";
         return *this;
     }
 };

 int main()
 {
     std::list<A> container;

     std::cout << "construct 2 times A:\\n";
     A two { "two" };
     A three { "three" };

     std::cout << "emplace:\\n";
     container.emplace(container.end(), "one");

     std::cout << "emplace with A&:\\n";
     container.emplace(container.end(), two);

     std::cout << "emplace with A&&:\\n";
     container.emplace(container.end(), std::move(three));

     std::cout << "content:\\n";
     for (const auto& obj : container)
         std::cout << ' ' << obj.s;
     std::cout << '\\n';
 }

.SH Output:

 construct 2 times A:
  constructed
  constructed
 emplace:
  constructed
 emplace with A&:
  copy constructed
 emplace with A&&:
  move constructed
 content:
  one two three

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

      DR    Applied to              Behavior as published              Correct behavior
   LWG 2164 C++11      it was not clear whether the arguments can      clarified
                       refer to the container

.SH See also

   insert       inserts elements
                \fI(public member function)\fP
   emplace_back constructs an element in-place at the end
   \fI(C++11)\fP      \fI(public member function)\fP
